agent-relay-server 0.63.0 → 0.63.1

package/docs/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Relay API",
-    "version": "0.63.0",
+    "version": "0.63.1",
     "description": "Real-time message bus for inter-agent communication. Agent-first: this spec is designed for machine consumption — agents can self-discover the full API surface via GET /api/spec.",
     "license": {
       "name": "MIT",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-server",
-  "version": "0.63.0",
+  "version": "0.63.1",
   "description": "Lightweight HTTP message relay for inter-agent communication across machines",
   "module": "src/index.ts",
   "type": "module",
@@ -33,7 +33,7 @@
     "CONTRIBUTING.md"
   ],
   "dependencies": {
-    "agent-relay-sdk": "0.2.41",
+    "agent-relay-sdk": "0.2.42",
     "ajv": "^8.20.0"
   },
   "scripts": {
@@ -92,6 +92,8 @@
   "author": "Edin Mujkanovic",
   "devDependencies": {
     "@types/bun": "latest",
+    "@types/madge": "^5.0.3",
+    "madge": "^8.0.0",
     "typescript": "^5"
   },
   "engines": {

package/runner/src/adapter.ts

@@ -1,6 +1,7 @@
 import type { AgentProfile, Message } from "agent-relay-sdk";
 import { isRecord } from "agent-relay-sdk";
 import type { SessionEvent } from "./session-insights";
+import { messageBodyMaxCharsFromEnv } from "./config";
 
 export type SemanticStatus = "idle" | "busy" | "offline" | "error";
 type ProviderWorkKind = "provider-turn" | "subagent";
@@ -202,7 +203,7 @@ export const DEFAULT_PROVIDER_MESSAGE_BODY_MAX_CHARS = 24_000;
 // Resolve the delivered-body cap. Deployment-dependent (the right ceiling tracks the host's
 // context budget), so it's overridable via env — set on the orchestrator/host that spawns runners.
 export function providerMessageBodyMaxChars(): number {
-  const raw = process.env.AGENT_RELAY_MESSAGE_BODY_MAX_CHARS;
+  const raw = messageBodyMaxCharsFromEnv();
   if (raw !== undefined) {
     const parsed = Number.parseInt(raw.trim(), 10);
     if (Number.isFinite(parsed) && parsed > 0) return parsed;

package/runner/src/config.ts

@@ -1,11 +1,26 @@
 import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir, hostname } from "node:os";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { DEFAULT_RELAY_URL, RELAY_TOKEN_HEADER, errMessage, stringValue } from "agent-relay-sdk";
 import type { SettingEntry, WorkspaceMetadata } from "agent-relay-sdk";
 import { sanitizeFsName } from "agent-relay-sdk/fs-name";
-import type { ProviderConfig } from "./adapter";
+
+interface ProviderConfig {
+  command: string;
+  defaultArgs: string[];
+  env: Record<string, string>;
+  pluginDirs: string[];
+  defaultCapabilities: string[];
+  defaultApprovalMode: string;
+  defaultTags: string[];
+  chatCaptureMode: "final" | "full";
+  reasoningCapture?: boolean;
+  headless: {
+    tmuxPrefix: string;
+    shutdownTimeoutMs: number;
+  };
+}
 
 interface GlobalRunnerConfig {
   relayUrl: string;
@@ -17,7 +32,7 @@ interface LoadedProviderConfig extends ProviderConfig {
   path: string;
 }
 
-function agentRelayHome(): string {
+export function agentRelayHome(): string {
   return process.env.AGENT_RELAY_HOME || join(homedir(), ".agent-relay");
 }
 
@@ -48,12 +63,135 @@ export function loadGlobalConfig(home = agentRelayHome()): GlobalRunnerConfig {
   const path = join(home, "config.json");
   const parsed = readJson(path);
   return {
-    relayUrl: stringValue(parsed.relayUrl) ?? process.env.AGENT_RELAY_URL ?? DEFAULT_RELAY_URL,
-    token: stringValue(parsed.token) ?? process.env.AGENT_RELAY_TOKEN,
+    relayUrl: stringValue(parsed.relayUrl) ?? relayUrlFromEnv() ?? DEFAULT_RELAY_URL,
+    token: stringValue(parsed.token) ?? relayTokenFromEnv(),
     defaultCwd: stringValue(parsed.defaultCwd) ?? process.cwd(),
   };
 }
 
+function relayUrlFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_URL;
+}
+
+export function relayTokenFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_TOKEN;
+}
+
+export function runtimeTokenProfileFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_TOKEN_PROFILE;
+}
+
+export function runtimeTokenJtiFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_TOKEN_JTI;
+}
+
+export function runtimeTokenExpiresAtFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_TOKEN_EXPIRES_AT;
+}
+
+export function agentProfileNameFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_AGENT_PROFILE;
+}
+
+export function agentProfileJsonFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_AGENT_PROFILE_JSON;
+}
+
+export function workspaceJsonFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_WORKSPACE_JSON;
+}
+
+export function tmuxSessionFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_TMUX_SESSION;
+}
+
+export function policyNameFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_POLICY;
+}
+
+export function spawnRequestIdFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_SPAWN_REQUEST_ID;
+}
+
+export function automationIdFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_AUTOMATION_ID;
+}
+
+export function automationRunIdFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_AUTOMATION_RUN_ID;
+}
+
+export function lifecycleFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_LIFECYCLE;
+}
+
+export function sessionDebugEnabled(): boolean {
+  return process.env.AGENT_RELAY_SESSION_DEBUG === "1";
+}
+
+export function logLevelFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_LOG_LEVEL;
+}
+
+export function mcpProxyEnabledFromEnv(): boolean {
+  return !["0", "false", "off"].includes((process.env.AGENT_RELAY_MCP_PROXY ?? "").trim().toLowerCase());
+}
+
+export function runnerInfoFileFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_RUNNER_INFO_FILE;
+}
+
+export function runnerOutboxDirFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_RUNNER_OUTBOX_DIR;
+}
+
+export function runnerOutboxDirWithInfoFallback(): string | undefined {
+  const dir = runnerOutboxDirFromEnv();
+  if (dir) return dir;
+  const infoFile = runnerInfoFileFromEnv();
+  return infoFile ? join(dirname(infoFile), "outbox") : undefined;
+}
+
+export function capsFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_CAPS;
+}
+
+export function tagsFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_TAGS;
+}
+
+export function workspaceModeFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_WORKSPACE_MODE;
+}
+
+export function orchestratorBaseDirFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_ORCHESTRATOR_BASE_DIR;
+}
+
+export function runnerLogFileFromEnv(): string | undefined {
+  return typeof process.env.AGENT_RELAY_LOG_FILE === "string" ? process.env.AGENT_RELAY_LOG_FILE : undefined;
+}
+
+export function orchestratorUrlFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_ORCHESTRATOR_URL;
+}
+
+export function contextStateDirFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_CONTEXT_STATE_DIR;
+}
+
+export function attachmentCacheDirFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_ATTACHMENT_CACHE_DIR;
+}
+
+export function providerHomeRootFromEnv(): string {
+  return process.env.AGENT_RELAY_PROVIDER_HOME_ROOT || join(homedir(), ".agent-relay", "provider-homes");
+}
+
+export function messageBodyMaxCharsFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_MESSAGE_BODY_MAX_CHARS;
+}
+
 export function loadProviderConfig(provider: string, home = agentRelayHome()): LoadedProviderConfig {
   const path = join(providersDir(home), `${provider}.json`);
   const raw = readJson(path);

package/src/artifact-storage.ts

@@ -4,6 +4,7 @@ import { tmpdir } from "node:os";
 import { dirname, join, relative, resolve } from "node:path";
 import { Readable } from "node:stream";
 import { expandTilde } from "./utils";
+import { artifactsDir, maxArtifactBytesFromEnv } from "./config";
 
 interface ArtifactStorageBackend {
   readonly scheme: string;
@@ -20,14 +21,11 @@ interface ArtifactStorageBackend {
 const DEFAULT_MAX_ARTIFACT_BYTES = 50 * 1024 * 1024;
 
 function artifactRoot(): string {
-  return expandTilde(process.env.AGENT_RELAY_ARTIFACTS_DIR || "~/.agent-relay/artifacts");
+  return expandTilde(artifactsDir());
 }
 
 export function maxArtifactBytes(): number {
-  const raw = process.env.AGENT_RELAY_MAX_ARTIFACT_BYTES;
-  if (!raw) return DEFAULT_MAX_ARTIFACT_BYTES;
-  const parsed = Number(raw);
-  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : DEFAULT_MAX_ARTIFACT_BYTES;
+  return maxArtifactBytesFromEnv(DEFAULT_MAX_ARTIFACT_BYTES);
 }
 
 export function normalizeDigest(digest: string): string {

package/src/bus.ts

@@ -15,6 +15,7 @@ import { applyCommandToRecipe } from "./recipe-runner";
 import { enqueueContinuationInjectionAfterClear } from "./self-resume";
 import { messageMatchesAgent, targetMatchesAgent } from "./agent-ref";
 import { probeWorkspaceOnTurnEnd } from "./workspace-probe";
+import { busStaleGraceMs } from "./config";
 import {
   BusProtocolError,
   parseBusFrame,
@@ -107,11 +108,9 @@ export function getBusConnectionCount(): number {
   return busConnections.size;
 }
 
-export function expireStaleBusAgents(graceMs = Number(process.env.AGENT_RELAY_STALE_GRACE_MS) || 120_000): { agentIds: string[]; orphanedTasks: Task[] } {
+export function expireStaleBusAgents(graceMs = busStaleGraceMs()): { agentIds: string[]; orphanedTasks: Task[] } {
   const cutoff = Date.now() - graceMs;
-  const rows = getDb()
-    .query("SELECT id FROM agents WHERE status = 'stale' AND last_seen < ? AND id NOT IN ('user', 'system')")
-    .all(cutoff) as Array<{ id: string }>;
+  const rows = getDb().query("SELECT id FROM agents WHERE status = 'stale' AND last_seen < ? AND id NOT IN ('user', 'system')").all(cutoff) as Array<{ id: string }>;
   const orphanedTasks: Task[] = [];
   for (const row of rows) {
     // Bus-grace staleness across a relay restart/reconnect — the process may be alive.

package/src/cli/_shared.ts

@@ -5,11 +5,12 @@
 import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import { RELAY_TOKEN_HEADER } from "agent-relay-sdk";
+import { cliRelayToken, cliRelayUrl } from "../config";
 
 export async function apiRequest(method: string, path: string, body?: unknown): Promise<unknown> {
-  const baseUrl = process.env.AGENT_RELAY_URL || "http://127.0.0.1:4850";
+  const baseUrl = cliRelayUrl();
   const headers: Record<string, string> = {};
-  const token = process.env.AGENT_RELAY_TOKEN;
+  const token = cliRelayToken();
   if (token) headers[RELAY_TOKEN_HEADER] = token;
   if (body !== undefined) headers["Content-Type"] = "application/json";
   const response = await fetch(new URL(path, baseUrl), {
@@ -27,9 +28,9 @@ export async function apiRequest(method: string, path: string, body?: unknown):
 }
 
 export async function apiRawRequest(method: string, path: string, body: BodyInit, extraHeaders: Record<string, string> = {}): Promise<unknown> {
-  const baseUrl = process.env.AGENT_RELAY_URL || "http://127.0.0.1:4850";
+  const baseUrl = cliRelayUrl();
   const headers: Record<string, string> = { ...extraHeaders };
-  const token = process.env.AGENT_RELAY_TOKEN;
+  const token = cliRelayToken();
   if (token) headers[RELAY_TOKEN_HEADER] = token;
   const response = await fetch(new URL(path, baseUrl), { method, headers, body });
   const text = await response.text();

package/src/cli/agent-detect.ts

@@ -5,6 +5,7 @@
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { apiRequest, uniqueStrings } from "./_shared";
+import { agentIdFromEnv, codexStatePathFromEnv, contextPathFromEnv } from "../config";
 
 export async function detectActivePairId(agentId: string): Promise<string | undefined> {
   const pairs = await apiRequest("GET", `/api/pairs?agent=${encodeURIComponent(agentId)}&status=active`) as Array<{ id?: string }>;
@@ -12,15 +13,16 @@ export async function detectActivePairId(agentId: string): Promise<string | unde
 }
 
 export async function detectAgentId(): Promise<string | undefined> {
-  const explicit = process.env.AGENT_RELAY_ID;
+  const explicit = agentIdFromEnv();
   if (explicit) return explicit;
 
   const contextMatch = currentAgentContextId();
   if (contextMatch) return contextMatch;
 
   const cwd = process.cwd();
-  const explicitCodexState = process.env.AGENT_RELAY_CODEX_STATE_PATH
-    ? readCodexState(process.env.AGENT_RELAY_CODEX_STATE_PATH)
+  const explicitCodexStatePath = codexStatePathFromEnv();
+  const explicitCodexState = explicitCodexStatePath
+    ? readCodexState(explicitCodexStatePath)
     : null;
   if (explicitCodexState?.agentId) return explicitCodexState.agentId;
 
@@ -48,7 +50,7 @@ export async function detectAgentId(): Promise<string | undefined> {
 }
 
 function currentAgentContextId(): string | undefined {
-  const explicitPath = process.env.AGENT_RELAY_CONTEXT_PATH;
+  const explicitPath = contextPathFromEnv();
   if (explicitPath) {
     const explicit = readAgentContext(explicitPath);
     if (explicit?.agentId && contextMatchesCurrentProcess(explicit)) return explicit.agentId;

package/src/cli/introspect.ts

@@ -2,6 +2,7 @@
 // end-of-session self-view as a bounded, structured Insights observation (#185).
 import { apiRequest, readStdin } from "./_shared";
 import { detectAgentId } from "./agent-detect";
+import { projectFromEnv, providerSessionIdFromEnv } from "../config";
 
 // Insights #185: capture the agent's end-of-session self-view as a bounded, structured
 // artifact (epic #183, docs/self-improvement.md). Manual rail in v0 — the agent or
@@ -61,8 +62,8 @@ export async function handleIntrospectCommand(args: string[]): Promise<void> {
   if (!from) throw new Error("Could not detect current Agent Relay ID. Pass --from AGENT_ID or set AGENT_RELAY_ID.");
 
   const observation = await apiRequest("POST", "/api/insights/observations", {
-    sessionId: sessionId || process.env.AGENT_RELAY_PROVIDER_SESSION_ID || `manual-${from}`,
-    project: project || process.env.AGENT_RELAY_PROJECT || process.cwd().split("/").filter(Boolean).at(-1) || process.cwd(),
+    sessionId: sessionId || providerSessionIdFromEnv() || `manual-${from}`,
+    project: project || projectFromEnv() || process.cwd().split("/").filter(Boolean).at(-1) || process.cwd(),
     agentId: from,
     signal: "introspection",
     source: "agent",

package/src/cli/token.ts

@@ -1,6 +1,7 @@
 // Token commands — auto-split from cli.ts (#294). create/list/revoke/verify for
 // component JWTs.
 import { apiRequest, splitTagArgs } from "./_shared";
+import { cliRelayToken } from "../config";
 
 export async function handleTokenCommand(args: string[]): Promise<void> {
   const action = args[0] ?? "list";
@@ -45,7 +46,7 @@ export async function handleTokenCommand(args: string[]): Promise<void> {
     return;
   }
   if (action === "verify") {
-    const token = rest.find((arg) => !arg.startsWith("--")) ?? process.env.AGENT_RELAY_TOKEN;
+    const token = rest.find((arg) => !arg.startsWith("--")) ?? cliRelayToken();
     if (!token) throw new Error("Usage: agent-relay token verify TOKEN");
     const payload = decodeJwtPayload(token);
     if (!payload) throw new Error("not a component JWT");

package/src/cli/workspace.ts

@@ -7,13 +7,14 @@ import { describeWorkspacePhase, readyContract, type WorkspacePhaseView } from "
 import type { WorkspaceDepsRefreshResult } from "agent-relay-sdk";
 import { AUTO_MERGE_POLICIES } from "../workspace-merge";
 import type { WorkspaceAutoMergePolicy } from "../types";
+import { workspaceJsonFromEnv } from "../config";
 
 export const WORKSPACE_USAGE = "Usage: agent-relay workspace <status|diagnostics|ready|land|claim|release|list|cleanup-stale|deps> [--id ID] [--strategy ...] [--auto-merge on-green|on-approval|manual] [--reviewer HANDLE] [--purpose TEXT] [--repo PATH] [--wait] [--timeout SECONDS] [--check] [--execute] [--json]";
 
 // The agent's own isolated-workspace id, published in AGENT_RELAY_WORKSPACE_JSON
 // by the orchestrator at spawn. Undefined for shared-workspace / non-managed agents.
 function currentWorkspaceId(): string | undefined {
-  const json = process.env.AGENT_RELAY_WORKSPACE_JSON;
+  const json = workspaceJsonFromEnv();
   if (!json) return undefined;
   try {
     const parsed = JSON.parse(json) as { id?: string };

package/src/config.ts

@@ -1,8 +1,10 @@
 // Shared runtime constants. Import from here rather than redefining.
 
 import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { DEFAULT_RELAY_URL, RELAY_TOKEN_HEADER } from "agent-relay-sdk";
 import { CONTRACT_VERSIONS } from "./contracts";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -19,6 +21,31 @@ function envPositiveInt(name: string, fallback: number): number {
   return Math.floor(parsed);
 }
 
+function envNumberOrDefault(name: string, fallback: number): number {
+  return Number(process.env[name]) || fallback;
+}
+
+function envNonNegativeNumber(name: string, fallback: number): number {
+  const parsed = Number(process.env[name]);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback;
+}
+
+function envSafePositiveInteger(name: string, fallback: number): number {
+  const raw = process.env[name];
+  if (!raw) return fallback;
+  const parsed = Number(raw);
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function envTrimmed(name: string): string {
+  return (process.env[name] || "").trim();
+}
+
+function envTrimmedOrUndefined(name: string): string | undefined {
+  const value = process.env[name]?.trim();
+  return value || undefined;
+}
+
 export const STALE_TTL_MS = envPositiveInt("STALE_TTL_MS", 120_000); // 2min without heartbeat → offline
 // #451 — default TTL for fire-and-forget FAN-OUT messages (broadcast/tag/cap/label/team) that the
 // sender didn't bound. A stale fan-out push must not wake an agent that matches the target hours
@@ -42,12 +69,160 @@ export const MAIN_MERGE_PAUSE_TTL_MS = envPositiveInt("AGENT_RELAY_MAIN_MERGE_PA
 export const MAX_BODY_BYTES = 64 * 1024;
 export const INTEGRATION_RATE_LIMIT_PER_MINUTE = envPositiveInt("AGENT_RELAY_INTEGRATION_RATE_LIMIT_PER_MINUTE", 120);
 
-export const AUTH_TOKEN = process.env.AGENT_RELAY_TOKEN || "";
+export const AUTOMATION_INTERVAL_MS = envNumberOrDefault("AGENT_RELAY_AUTOMATION_INTERVAL_MS", 30 * 1000);
+export const IDLE_TIMEOUT_SECONDS = envNumberOrDefault("AGENT_RELAY_IDLE_TIMEOUT_SECONDS", 255);
+export const LOG_REQUESTS = process.env.AGENT_RELAY_LOG_REQUESTS === "1";
+
+const AUTH_TOKEN = process.env.AGENT_RELAY_TOKEN || "";
 export const CORS_ORIGINS = (process.env.AGENT_RELAY_CORS_ORIGINS || "")
   .split(",")
   .map((origin) => origin.trim())
   .filter(Boolean);
 
+export function relayToken(): string {
+  return process.env.AGENT_RELAY_TOKEN ?? AUTH_TOKEN;
+}
+
+export function relayAuthHeaders(base: Record<string, string> = {}): Record<string, string> {
+  const token = relayToken();
+  return token ? { ...base, [RELAY_TOKEN_HEADER]: token } : base;
+}
+
+export function allowUnauthenticated(): boolean {
+  return process.env.AGENT_RELAY_ALLOW_UNAUTH === "1";
+}
+
+export function tokenSecretFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_TOKEN_SECRET;
+}
+
+export function corsOriginsFromEnv(): string[] | undefined {
+  const raw = process.env.AGENT_RELAY_CORS_ORIGINS;
+  if (raw === undefined) return undefined;
+  return raw.split(",").map((origin) => origin.trim()).filter(Boolean);
+}
+
+export function connectorsDirFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_CONNECTORS_DIR;
+}
+
+export function connectorActionTimeoutMs(fallback: number): number {
+  const raw = Number(process.env.AGENT_RELAY_CONNECTOR_ACTION_TIMEOUT_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : fallback;
+}
+
+export function rateLimitFallbackMs(): number {
+  return envNumberOrDefault("AGENT_RELAY_RATE_LIMIT_FALLBACK_MS", 60 * 60 * 1000);
+}
+
+export function artifactsDir(): string {
+  return process.env.AGENT_RELAY_ARTIFACTS_DIR || "~/.agent-relay/artifacts";
+}
+
+export function maxArtifactBytesFromEnv(fallback: number): number {
+  return envSafePositiveInteger("AGENT_RELAY_MAX_ARTIFACT_BYTES", fallback);
+}
+
+export const OUTBOX_RETENTION_MS = envNumberOrDefault("AGENT_RELAY_OUTBOX_RETENTION_MS", 60 * 60 * 1000);
+export const TOKEN_RECORD_RETENTION_SECONDS = envNumberOrDefault("AGENT_RELAY_TOKEN_RECORD_RETENTION_SECONDS", 7 * 24 * 60 * 60);
+export const CONFLICT_SCAN_INTERVAL_MS = envNumberOrDefault("AGENT_RELAY_CONFLICT_SCAN_INTERVAL_MS", 10 * 60 * 1000);
+export const WORKSPACE_RETENTION_MS = envNumberOrDefault("AGENT_RELAY_WORKSPACE_RETENTION_MS", DAY_MS);
+export const DB_MAINTENANCE_INTERVAL_MS = envNumberOrDefault("AGENT_RELAY_DB_MAINTENANCE_INTERVAL_MS", DAY_MS);
+export const DB_VACUUM_EVERY = envNumberOrDefault("AGENT_RELAY_DB_VACUUM_EVERY", 7);
+export const WORKSPACE_REVIEW_TTL_MS = envNumberOrDefault("AGENT_RELAY_WORKSPACE_REVIEW_TTL_MS", 3 * DAY_MS);
+export const WORKSPACE_GC_INTERVAL_MS = envNumberOrDefault("AGENT_RELAY_WORKSPACE_GC_INTERVAL_MS", 60 * 60 * 1000);
+export const WORKSPACE_ORPHAN_REAPER_INTERVAL_MS = envNumberOrDefault("AGENT_RELAY_WORKSPACE_ORPHAN_REAPER_INTERVAL_MS", 30 * 60 * 1000);
+export const WORKSPACE_AUTO_MERGE_INTERVAL_MS = envNumberOrDefault("AGENT_RELAY_WORKSPACE_AUTO_MERGE_INTERVAL_MS", CONFLICT_SCAN_INTERVAL_MS);
+export const ORPHAN_REAPER_INTERVAL_MS = envNumberOrDefault("AGENT_RELAY_ORPHAN_REAPER_INTERVAL_MS", 5 * 60 * 1000);
+export const STEWARD_WAKE_COOLDOWN_MS = envNumberOrDefault("AGENT_RELAY_STEWARD_WAKE_COOLDOWN_MS", 10 * 60 * 1000);
+export const UNLANDED_FLAG_COOLDOWN_MS = envNumberOrDefault("AGENT_RELAY_ORPHAN_FLAG_COOLDOWN_MS", 6 * 60 * 60 * 1000);
+export const STEWARD_CLAIM_TTL_MS = envNumberOrDefault("AGENT_RELAY_WORKSPACE_CLAIM_TTL_MS", 15 * 60_000);
+export const DB_SLOW_QUERY_MS = envNumberOrDefault("AGENT_RELAY_DB_SLOW_MS", 0);
+
+export function stewardEscalationMs(): number {
+  return envNumberOrDefault("AGENT_RELAY_WORKSPACE_STEWARD_ESCALATION_MS", 60 * 60 * 1000);
+}
+
+export function stewardFallbackTarget(): string {
+  return envTrimmed("AGENT_RELAY_WORKSPACE_STEWARD_FALLBACK");
+}
+
+export function envMsOrDefault(name: string, fallback: number): number {
+  return envNonNegativeNumber(name, fallback);
+}
+
+export function orphanGraceMs(): number {
+  return envMsOrDefault("AGENT_RELAY_ORPHAN_GRACE_MS", 30 * 60 * 1000);
+}
+
+export function orphanReapCooldownMs(): number {
+  return envMsOrDefault("AGENT_RELAY_ORPHAN_REAP_COOLDOWN_MS", 5 * 60 * 1000);
+}
+
+export function orphanReapEnabled(): boolean {
+  return process.env.AGENT_RELAY_ORPHAN_REAP !== "0";
+}
+
+export function orphanWorktreeReapEnabled(): boolean {
+  return process.env.AGENT_RELAY_ORPHAN_WORKTREE_REAP !== "0";
+}
+
+export function workspaceAutoMergeEnabled(): boolean {
+  return process.env.AGENT_RELAY_WORKSPACE_AUTO_MERGE !== "0";
+}
+
+export function continuationArchiveFtsEnabled(): boolean {
+  return process.env.AGENT_RELAY_DISABLE_CONTINUATION_ARCHIVE_FTS !== "1";
+}
+
+export function busStaleGraceMs(): number {
+  return envNumberOrDefault("AGENT_RELAY_STALE_GRACE_MS", 120_000);
+}
+
+export function defaultIssueRepo(): string | undefined {
+  return process.env.AGENT_RELAY_DEFAULT_ISSUE_REPO || process.env.GITHUB_REPOSITORY || undefined;
+}
+
+export function cliRelayUrl(): string {
+  return process.env.AGENT_RELAY_URL || DEFAULT_RELAY_URL;
+}
+
+export function cliRelayToken(): string | undefined {
+  return process.env.AGENT_RELAY_TOKEN;
+}
+
+export function workspaceJsonFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_WORKSPACE_JSON;
+}
+
+export function providerSessionIdFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_PROVIDER_SESSION_ID;
+}
+
+export function projectFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_PROJECT;
+}
+
+export function agentIdFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_ID;
+}
+
+export function codexStatePathFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_CODEX_STATE_PATH;
+}
+
+export function contextPathFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_CONTEXT_PATH;
+}
+
+export function localOrchestratorIdFromEnv(): string | undefined {
+  return envTrimmedOrUndefined("AGENT_RELAY_ORCHESTRATOR_ID");
+}
+
+export function providerConfigHomeFromEnv(): string {
+  return process.env.AGENT_RELAY_HOME || join(process.env.HOME || ".", ".agent-relay");
+}
+
 export type IntegrationTokenConfig = {
   name: string;
   token: string;

package/src/connectors.ts

@@ -5,6 +5,7 @@ import type { ConnectorAction, ConnectorActionResult, ConnectorManifest, Connect
 import { ValidationError } from "./db";
 import { isRecord } from "agent-relay-sdk";
 import { registerConnectorConfigSetting, validateConnectorConfig } from "./settings/modules";
+import { connectorActionTimeoutMs as configuredConnectorActionTimeoutMs, connectorsDirFromEnv } from "./config";
 
 const CONNECTOR_SCHEMA = "agent-relay.connector.v1";
 const VALID_KINDS = new Set(["channel", "event", "provider", "orchestrator"]);
@@ -12,7 +13,7 @@ const VALID_ACTIONS = new Set(["install", "uninstall", "enable", "disable", "sta
 const DEFAULT_ACTION_TIMEOUT_MS = 30_000;
 
 function connectorRegistryDir(): string {
-  const configured = process.env.AGENT_RELAY_CONNECTORS_DIR;
+  const configured = connectorsDirFromEnv();
   if (configured) return resolveHome(configured);
   return join(homedir(), ".agent-relay", "connectors");
 }
@@ -177,8 +178,7 @@ export function writeConnectorConfig(id: string, config: Record<string, unknown>
 }
 
 function connectorActionTimeoutMs(): number {
-  const raw = Number(process.env.AGENT_RELAY_CONNECTOR_ACTION_TIMEOUT_MS);
-  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_ACTION_TIMEOUT_MS;
+  return configuredConnectorActionTimeoutMs(DEFAULT_ACTION_TIMEOUT_MS);
 }
 
 const LIFECYCLE_ACTIONS = new Set(["install", "uninstall", "start", "stop", "restart", "enable", "disable"]);

package/src/db/connection.ts

@@ -1,4 +1,5 @@
 import { Database } from "bun:sqlite";
+import { DB_SLOW_QUERY_MS } from "../config";
 
 // The shared SQLite handle. Set once by initDb() (schema.ts) and read everywhere
 // else through getDb(). Kept module-private so the only mutation path is setDb().
@@ -33,7 +34,7 @@ export function applyConnectionPragmas(conn: Database): void {
 // Slow-query log. Off unless AGENT_RELAY_DB_SLOW_MS is set (>0). Wraps the
 // execution of the heavy dynamic queries so the next slow query surfaces before
 // it wedges something (see issue #197 — the 8.6s reply-obligation query).
-const SLOW_QUERY_MS = Number(process.env.AGENT_RELAY_DB_SLOW_MS) || 0;
+const SLOW_QUERY_MS = DB_SLOW_QUERY_MS;
 export function timedQuery<T>(label: string, run: () => T): T {
   if (SLOW_QUERY_MS <= 0) return run();
   const start = performance.now();

package/src/db/continuation-archives.ts

@@ -1,4 +1,4 @@
-import { MAX_BODY_BYTES } from "../config";
+import { MAX_BODY_BYTES, continuationArchiveFtsEnabled } from "../config";
 import { getContinuationEnvelope } from "./continuations.ts";
 import { getDb, ValidationError } from "./connection.ts";
 
@@ -28,7 +28,7 @@ interface ContinuationArchiveRow {
 const MAX_RECALL_LIMIT = 20;
 
 export function ensureContinuationArchiveSearchSchema(): void {
-  if (process.env.AGENT_RELAY_DISABLE_CONTINUATION_ARCHIVE_FTS === "1") return;
+  if (!continuationArchiveFtsEnabled()) return;
   try {
     getDb().query(`
       CREATE VIRTUAL TABLE IF NOT EXISTS continuation_archive_segments
@@ -116,7 +116,7 @@ export function searchContinuationArchives(input: {
 }
 
 function continuationArchiveSearchMode(): "fts5" | "like" {
-  if (process.env.AGENT_RELAY_DISABLE_CONTINUATION_ARCHIVE_FTS === "1") return "like";
+  if (!continuationArchiveFtsEnabled()) return "like";
   const row = getDb().query(`
     SELECT 1 FROM sqlite_master
     WHERE type = 'table' AND name = 'continuation_archive_segments'

package/src/index.ts

@@ -15,7 +15,11 @@ import { startPlanLiveBindings } from "./services/plan-live-bindings";
 import { resolve, sep } from "path";
 import { gzipSync, brotliCompressSync, constants as zlibConstants } from "node:zlib";
 import {
+  AUTOMATION_INTERVAL_MS,
+  IDLE_TIMEOUT_SECONDS,
+  LOG_REQUESTS,
   VERSION,
+  relayToken,
 } from "./config";
 import { CONTRACT_VERSIONS } from "./contracts";
 import {
@@ -69,9 +73,6 @@ function startServer(): void {
   const PORT = Number(process.env.PORT) || 4850;
   const HOST = process.env.HOST || "127.0.0.1";
   const DB_PATH = process.env.DB_PATH || "agent-relay.db";
-  const AUTOMATION_INTERVAL_MS = Number(process.env.AGENT_RELAY_AUTOMATION_INTERVAL_MS) || 30 * 1000;
-  const IDLE_TIMEOUT_SECONDS = Number(process.env.AGENT_RELAY_IDLE_TIMEOUT_SECONDS) || 255;
-  const LOG_REQUESTS = process.env.AGENT_RELAY_LOG_REQUESTS === "1";
 
   assertSafeNetworkConfig(HOST);
   initDb(DB_PATH);
@@ -246,9 +247,9 @@ export function createFetchHandler(
       upstream.protocol = upstream.protocol === "https:" ? "wss:" : "ws:";
       // Pass the relay token as a header (not a query param) so it never lands in
       // access/proxy logs (#149). The orchestrator accepts both, but headers are safer.
-      const relayToken = process.env.AGENT_RELAY_TOKEN;
+      const token = relayToken();
       const upgraded = server.upgrade(req, {
-        data: { kind: "terminal-proxy", upstreamUrl: upstream.toString(), upstreamToken: relayToken, pending: [] },
+        data: { kind: "terminal-proxy", upstreamUrl: upstream.toString(), upstreamToken: token, pending: [] },
       });
       if (!upgraded) return new Response("WebSocket upgrade failed", { status: 400 });
       return undefined;

package/src/maintenance/constants.ts

@@ -1,4 +1,24 @@
-import { DAY_MS, REAP_INTERVAL_MS } from "../config";
+import {
+  CONFLICT_SCAN_INTERVAL_MS,
+  DAY_MS,
+  DB_MAINTENANCE_INTERVAL_MS,
+  DB_VACUUM_EVERY,
+  ORPHAN_REAPER_INTERVAL_MS,
+  OUTBOX_RETENTION_MS,
+  REAP_INTERVAL_MS,
+  TOKEN_RECORD_RETENTION_SECONDS,
+  WORKSPACE_AUTO_MERGE_INTERVAL_MS,
+  WORKSPACE_GC_INTERVAL_MS,
+  WORKSPACE_ORPHAN_REAPER_INTERVAL_MS,
+  WORKSPACE_RETENTION_MS,
+  WORKSPACE_REVIEW_TTL_MS,
+  envMsOrDefault,
+  orphanReapCooldownMs,
+  orphanReapEnabled,
+  orphanGraceMs,
+  stewardEscalationMs,
+  stewardFallbackTarget,
+} from "../config";
 import { READY_TO_LAND_STATUSES, TERMINAL_WORKSPACE_STATUSES } from "../workspace-phase";
 import type { WorkspaceStatus } from "../types";
 
@@ -6,30 +26,27 @@ export { DAY_MS, REAP_INTERVAL_MS, TERMINAL_WORKSPACE_STATUSES };
 
 export const DEFAULT_TIMEOUT_MS = 30_000;
 export const SCHEDULER_TICK_MS = 10_000;
-export const OUTBOX_RETENTION_MS = Number(process.env.AGENT_RELAY_OUTBOX_RETENTION_MS) || 60 * 60 * 1000;
-export const TOKEN_RECORD_RETENTION_SECONDS = Number(process.env.AGENT_RELAY_TOKEN_RECORD_RETENTION_SECONDS) || 7 * 24 * 60 * 60;
-export const CONFLICT_SCAN_INTERVAL_MS = Number(process.env.AGENT_RELAY_CONFLICT_SCAN_INTERVAL_MS) || 10 * 60 * 1000;
-export const WORKSPACE_RETENTION_MS = Number(process.env.AGENT_RELAY_WORKSPACE_RETENTION_MS) || DAY_MS;
-export const DB_MAINTENANCE_INTERVAL_MS = Number(process.env.AGENT_RELAY_DB_MAINTENANCE_INTERVAL_MS) || DAY_MS;
-export const DB_VACUUM_EVERY = Number(process.env.AGENT_RELAY_DB_VACUUM_EVERY) || 7;
-export const WORKSPACE_REVIEW_TTL_MS = Number(process.env.AGENT_RELAY_WORKSPACE_REVIEW_TTL_MS) || 3 * DAY_MS;
-export const WORKSPACE_GC_INTERVAL_MS = Number(process.env.AGENT_RELAY_WORKSPACE_GC_INTERVAL_MS) || 60 * 60 * 1000;
-export const WORKSPACE_ORPHAN_REAPER_INTERVAL_MS = Number(process.env.AGENT_RELAY_WORKSPACE_ORPHAN_REAPER_INTERVAL_MS) || 30 * 60 * 1000;
-export const WORKSPACE_AUTO_MERGE_INTERVAL_MS = Number(process.env.AGENT_RELAY_WORKSPACE_AUTO_MERGE_INTERVAL_MS) || CONFLICT_SCAN_INTERVAL_MS;
-export const ORPHAN_REAPER_INTERVAL_MS = Number(process.env.AGENT_RELAY_ORPHAN_REAPER_INTERVAL_MS) || 5 * 60 * 1000;
-
-export const stewardEscalationMs = () => Number(process.env.AGENT_RELAY_WORKSPACE_STEWARD_ESCALATION_MS) || 60 * 60 * 1000;
-export const stewardFallbackTarget = () => (process.env.AGENT_RELAY_WORKSPACE_STEWARD_FALLBACK || "").trim();
 export const STRANDABLE_STATUSES = new Set<WorkspaceStatus>([...READY_TO_LAND_STATUSES, "conflict"]);
 export const CONFLICT_SCAN_STATUSES = new Set<WorkspaceStatus>(["active", "ready", "review_requested", "merge_planned", "conflict"]);
 export const LANDED_RECONCILE_STATUSES = new Set<WorkspaceStatus>(["merge_planned", "review_requested", "conflict"]);
 
-export const envMsOrDefault = (name: string, fallback: number): number => {
-  const v = Number(process.env[name]);
-  return Number.isFinite(v) && v >= 0 ? v : fallback;
-};
-export const orphanGraceMs = () => envMsOrDefault("AGENT_RELAY_ORPHAN_GRACE_MS", 30 * 60 * 1000);
-export const orphanReapCooldownMs = () => envMsOrDefault("AGENT_RELAY_ORPHAN_REAP_COOLDOWN_MS", 5 * 60 * 1000);
 export const teamReapGraceMs = () => envMsOrDefault("TEAM_REAP_GRACE_MS", 30 * 60 * 1000);
 export const teamReapIntervalMs = () => envMsOrDefault("TEAM_REAP_INTERVAL_MS", 5 * 60 * 1000);
-export const orphanReapEnabled = () => process.env.AGENT_RELAY_ORPHAN_REAP !== "0";
+export {
+  CONFLICT_SCAN_INTERVAL_MS,
+  DB_MAINTENANCE_INTERVAL_MS,
+  DB_VACUUM_EVERY,
+  ORPHAN_REAPER_INTERVAL_MS,
+  OUTBOX_RETENTION_MS,
+  TOKEN_RECORD_RETENTION_SECONDS,
+  WORKSPACE_AUTO_MERGE_INTERVAL_MS,
+  WORKSPACE_GC_INTERVAL_MS,
+  WORKSPACE_ORPHAN_REAPER_INTERVAL_MS,
+  WORKSPACE_RETENTION_MS,
+  WORKSPACE_REVIEW_TTL_MS,
+  orphanGraceMs,
+  orphanReapCooldownMs,
+  orphanReapEnabled,
+  stewardEscalationMs,
+  stewardFallbackTarget,
+};

package/src/provider-config-store.ts

@@ -3,6 +3,7 @@ import { hostname } from "node:os";
 import { join } from "node:path";
 import { ValidationError, listOrchestrators } from "./db";
 import { getConfig, listConfig, setConfig } from "./config-store";
+import { providerConfigHomeFromEnv } from "./config";
 import { cleanString, cleanStringArray, optionalEnum } from "./validation";
 import { emitConfigChanged } from "./sse";
 import {
@@ -234,5 +235,5 @@ function maskEnv(env: Record<string, string>): Record<string, string> {
 }
 
 function agentRelayHome(): string {
-  return process.env.AGENT_RELAY_HOME || join(process.env.HOME || ".", ".agent-relay");
+  return providerConfigHomeFromEnv();
 }

package/src/provider-state.ts

@@ -1,4 +1,5 @@
 import { isRecord } from "agent-relay-sdk";
+import { rateLimitFallbackMs } from "./config";
 
 // One server-side home for reading an agent's provider runtime state (the
 // `meta.providerState` that both Claude and Codex ride for blocked/approval
@@ -48,9 +49,6 @@ export function isRateLimitHold(agent: HasMeta | null | undefined): boolean {
 // rather than waiting the full (unknown) limit window. Re-entering the hold on a
 // still-limited retry is cheap, and a subscription limit almost always carries a
 // reset time. Read at call-time so operators/tests can tune it.
-const rateLimitFallbackMs = (): number =>
-  Number(process.env.AGENT_RELAY_RATE_LIMIT_FALLBACK_MS) || 60 * 60 * 1000;
-
 /**
  * When a rate-limit hold should be lifted. The provider's `resetAt` is
  * authoritative; otherwise fall back to `enteredAt + fallback window`. Null only

package/src/routes/agent-sessions.ts

@@ -14,6 +14,7 @@ import { authContextFromRequest } from "../services/auth-context";
 import { ShutdownAuthError, ShutdownTargetError, shutdownAgent } from "../services/shutdown-agent";
 import { type AgentCard, type SpawnApprovalMode } from "../types";
 import { type ProviderEffort } from "agent-relay-sdk/provider-catalog";
+import { relayToken } from "../config";
 
 const CLAUDE_RESUME_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
@@ -486,8 +487,8 @@ async function proxyOrchestratorDelete(req: Request, orchestratorId: string, pat
   const incoming = new URL(req.url);
   const proxyUrl = `${orch.apiUrl}${path}${incoming.search}`;
   const headers: Record<string, string> = {};
-  const relayToken = process.env.AGENT_RELAY_TOKEN;
-  if (relayToken) headers[RELAY_TOKEN_HEADER] = relayToken;
+  const token = relayToken();
+  if (token) headers[RELAY_TOKEN_HEADER] = token;
   try {
     const res = await fetch(proxyUrl, {
       method: "DELETE",
@@ -507,8 +508,8 @@ async function proxyOrchestratorJson(orchestratorId: string, path: string, metho
   if (!orch.apiUrl) return error("orchestrator does not expose an API", 422);
   if (orch.status !== "online") return error("orchestrator is offline", 422);
   const headers: Record<string, string> = { "Content-Type": "application/json" };
-  const relayToken = process.env.AGENT_RELAY_TOKEN;
-  if (relayToken) headers[RELAY_TOKEN_HEADER] = relayToken;
+  const token = relayToken();
+  if (token) headers[RELAY_TOKEN_HEADER] = token;
   try {
     const res = await fetch(`${orch.apiUrl}${path}`, {
       method,

package/src/routes/orchestrator-proxy.ts

@@ -5,6 +5,7 @@ import { authorizeRoute, cleanJsonArray, error, json, type Handler } from "./_sh
 import { cleanStringArray } from "../validation";
 import { emitOrchestratorStatus } from "../sse";
 import { type OrchestratorRuntimeInput, type SpawnProvider } from "../types";
+import { relayToken } from "../config";
 
 export const getOrchestratorDirectories: Handler = async (req, params) => {
   const orch = getOrchestrator(params.id!);
@@ -63,8 +64,8 @@ async function proxyOrchestratorGet(req: Request, orchestratorId: string, path:
   const incoming = new URL(req.url);
   const proxyUrl = `${orch.apiUrl}${path}${incoming.search}`;
   const headers: Record<string, string> = {};
-  const relayToken = process.env.AGENT_RELAY_TOKEN;
-  if (relayToken) headers[RELAY_TOKEN_HEADER] = relayToken;
+  const token = relayToken();
+  if (token) headers[RELAY_TOKEN_HEADER] = token;
   try {
     const res = await fetch(proxyUrl, { headers, signal: AbortSignal.timeout(10_000) });
     const contentType = res.headers.get("content-type") ?? "";
@@ -88,8 +89,8 @@ async function proxyOrchestratorPost(req: Request, orchestratorId: string, path:
   const headers: Record<string, string> = {
     "Content-Type": req.headers.get("content-type") ?? "application/json",
   };
-  const relayToken = process.env.AGENT_RELAY_TOKEN;
-  if (relayToken) headers[RELAY_TOKEN_HEADER] = relayToken;
+  const token = relayToken();
+  if (token) headers[RELAY_TOKEN_HEADER] = token;
   try {
     const body = await req.text();
     const res = await fetch(proxyUrl, {

package/src/routes/workspaces.ts

@@ -13,6 +13,7 @@ import { resolve } from "node:path";
 import { type WorkspaceAutoMergePolicy, type WorkspaceDiagnostics, type WorkspaceGitState, type WorkspaceMergeStrategy, type WorkspaceRecord, type WorkspaceStatus } from "../types";
 import { AUTO_MERGE_POLICIES } from "../workspace-merge";
 import { workspaceActiveClaim } from "../workspace-claim";
+import { relayToken } from "../config";
 
 export const getWorkspaces: Handler = (req) => {
   try {
@@ -50,8 +51,8 @@ async function proxyWorkspaceHostGet(workspaceId: string, hostPath: string, extr
   if (workspace.baseSha) query.set("baseSha", workspace.baseSha);
   for (const [key, value] of Object.entries(extraQuery ?? {})) query.set(key, value);
   const headers: Record<string, string> = {};
-  const relayToken = process.env.AGENT_RELAY_TOKEN;
-  if (relayToken) headers[RELAY_TOKEN_HEADER] = relayToken;
+  const token = relayToken();
+  if (token) headers[RELAY_TOKEN_HEADER] = token;
   try {
     const res = await fetch(`${orch.apiUrl}${hostPath}?${query.toString()}`, {
       headers,
@@ -145,8 +146,8 @@ async function fetchWorkspaceGitState(workspace: WorkspaceRecord): Promise<{ sta
   if (workspace.baseRef) query.set("baseRef", workspace.baseRef);
   if (workspace.baseSha) query.set("baseSha", workspace.baseSha);
   const headers: Record<string, string> = {};
-  const relayToken = process.env.AGENT_RELAY_TOKEN;
-  if (relayToken) headers[RELAY_TOKEN_HEADER] = relayToken;
+  const token = relayToken();
+  if (token) headers[RELAY_TOKEN_HEADER] = token;
   try {
     const res = await fetch(`${orch.apiUrl}/api/workspace/state?${query.toString()}`, { headers, signal: AbortSignal.timeout(10_000) });
     if (!res.ok) return { unavailable: `host returned ${res.status}` };

package/src/security.ts

@@ -1,4 +1,12 @@
-import { AUTH_TOKEN, CORS_ORIGINS, getIntegrationTokens, type IntegrationTokenConfig } from "./config";
+import {
+  CORS_ORIGINS,
+  allowUnauthenticated,
+  corsOriginsFromEnv,
+  getIntegrationTokens,
+  relayToken,
+  tokenSecretFromEnv,
+  type IntegrationTokenConfig,
+} from "./config";
 import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
@@ -14,7 +22,7 @@ export function isLoopbackHost(hostname: string): boolean {
 }
 
 export function assertSafeNetworkConfig(host: string): void {
-  if (authToken() || process.env.AGENT_RELAY_ALLOW_UNAUTH === "1") return;
+  if (authToken() || allowUnauthenticated()) return;
   if (isLoopbackHost(host)) return;
   throw new Error(
     `Refusing to bind unauthenticated relay on ${host}. Set AGENT_RELAY_TOKEN or AGENT_RELAY_ALLOW_UNAUTH=1.`,
@@ -407,7 +415,7 @@ export function unauthorized(req: Request): Response {
 }
 
 function authToken(): string {
-  return process.env.AGENT_RELAY_TOKEN ?? AUTH_TOKEN;
+  return relayToken();
 }
 
 function extractToken(req: Request): string | null {
@@ -417,7 +425,7 @@ function extractToken(req: Request): string | null {
 }
 
 function tokenSecret(): string {
-  const env = process.env.AGENT_RELAY_TOKEN_SECRET;
+  const env = tokenSecretFromEnv();
   if (env) return env;
   const path = join(process.env.HOME || ".", ".agent-relay", "token-secret");
   if (existsSync(path)) return readFileSync(path, "utf8").trim();
@@ -542,7 +550,5 @@ function isTokenRevoked(jti: string): boolean {
 }
 
 function corsOrigins(): string[] {
-  const raw = process.env.AGENT_RELAY_CORS_ORIGINS;
-  if (raw === undefined) return CORS_ORIGINS;
-  return raw.split(",").map((origin) => origin.trim()).filter(Boolean);
+  return corsOriginsFromEnv() ?? CORS_ORIGINS;
 }

package/src/services/issue-lifecycle.ts

@@ -9,6 +9,7 @@ import {
 import { getIssueRef, resolveIssueRefByExternalKey, resolveIssueRefFromString, updateIssueRef } from "../db/issue-refs";
 import { associateIssue } from "../db/issue-associations";
 import { resolveIssueTrackerAdapter } from "../issue-tracker";
+import { defaultIssueRepo } from "../config";
 import type { IssueTrackerAdapter } from "../issue-tracker";
 import { recordAndEmitIssueActivity } from "./issue-activity";
 import type { IssueAssociationEntityType, IssueProvider, IssueRef, WorkspaceRecord } from "../types";
@@ -78,10 +79,6 @@ function logFailure(opts: IssueLifecycleOptions, message: string): void {
   else console.warn(message);
 }
 
-function defaultIssueRepo(): string | undefined {
-  return process.env.AGENT_RELAY_DEFAULT_ISSUE_REPO || process.env.GITHUB_REPOSITORY || undefined;
-}
-
 /**
  * `owner/repo` out of any git remote URL form: `git@github.com:owner/repo.git`,
  * `https://github.com/owner/repo.git`, `ssh://git@host/owner/repo`, trailing slash/`.git`

package/src/services/plan-graph.ts

@@ -4,6 +4,7 @@ import { associateIssue, planNodeIssueEntityId, removeAssociation } from "../db/
 import { resolveIssueRefFromString } from "../db/issue-refs";
 import { emitRelayEvent } from "../events";
 import { cleanString, cleanStringArray, optionalEnum } from "../validation";
+import { defaultIssueRepo } from "../config";
 import type { AuthContext } from "./auth-context";
 import type { AgentCard, Plan, PlanEdge, PlanNode, PlanOwnerRef, PlanStatus } from "../types";
 
@@ -86,10 +87,6 @@ function cleanRefs(value: unknown): PlanNode["refs"] | undefined {
   return Object.keys(out).length ? out : undefined;
 }
 
-function defaultIssueRepo(): string | undefined {
-  return process.env.AGENT_RELAY_DEFAULT_ISSUE_REPO || process.env.GITHUB_REPOSITORY || undefined;
-}
-
 function syncPlanNodeIssueAssociation(planId: string, node: PlanNode): void {
   if (!node.refs?.issueId) return;
   associateIssue(node.refs.issueId, "plan-node", planNodeIssueEntityId(planId, node.id));

package/src/upgrade.ts

@@ -1,10 +1,10 @@
 import { existsSync, readFileSync } from "node:fs";
 import { homedir, hostname as osHostname } from "node:os";
 import { join, resolve } from "node:path";
-import { VERSION } from "./config";
+import { VERSION, cliRelayUrl, localOrchestratorIdFromEnv, relayAuthHeaders } from "./config";
 import type { RuntimeContracts, RuntimePackageMetadata } from "./contracts";
 import { defaultRuntimePrefix, runtimeBinPath } from "./runtime-prefix";
-import { errMessage, RELAY_TOKEN_HEADER } from "agent-relay-sdk";
+import { errMessage } from "agent-relay-sdk";
 import { shellEscape as shellQuote } from "agent-relay-sdk/shell-utils";
 
 export type UpgradeProvider = "auto" | "all" | "codex" | "claude" | "orchestrator";
@@ -462,9 +462,8 @@ async function npmViewVersion(spec: string): Promise<string | undefined> {
 
 async function runningServerVersion(): Promise<string | undefined> {
   try {
-    const headers: Record<string, string> = {};
-    if (process.env.AGENT_RELAY_TOKEN) headers[RELAY_TOKEN_HEADER] = process.env.AGENT_RELAY_TOKEN;
-    const relayUrl = (process.env.AGENT_RELAY_URL || "http://127.0.0.1:4850").replace(/\/+$/, "");
+    const headers = relayAuthHeaders();
+    const relayUrl = cliRelayUrl().replace(/\/+$/, "");
     const response = await fetch(`${relayUrl}/api/stats`, { headers });
     if (!response.ok) return undefined;
     const payload = await response.json() as { version?: string };
@@ -476,9 +475,8 @@ async function runningServerVersion(): Promise<string | undefined> {
 
 async function runningOrchestrators(): Promise<UpgradeSnapshot["runningOrchestrators"]> {
   try {
-    const headers: Record<string, string> = {};
-    if (process.env.AGENT_RELAY_TOKEN) headers[RELAY_TOKEN_HEADER] = process.env.AGENT_RELAY_TOKEN;
-    const relayUrl = (process.env.AGENT_RELAY_URL || "http://127.0.0.1:4850").replace(/\/+$/, "");
+    const headers = relayAuthHeaders();
+    const relayUrl = cliRelayUrl().replace(/\/+$/, "");
     const response = await fetch(`${relayUrl}/api/orchestrators`, { headers });
     if (!response.ok) return [];
     const payload = await response.json() as Array<{
@@ -588,7 +586,7 @@ export function resolveLocalOrchestratorId(homeDirOverride?: string): string {
       // Unparsable config — fall through to env/hostname.
     }
   }
-  const envId = process.env.AGENT_RELAY_ORCHESTRATOR_ID?.trim();
+  const envId = localOrchestratorIdFromEnv();
   if (envId) return envId;
   return osHostname().replace(/\./g, "-");
 }

package/src/workspace-auto-merge.ts

@@ -36,11 +36,10 @@ import { workspaceActiveClaim } from "./workspace-claim";
 import { DIRTY_WORKTREE_LAND_SKIP_REASON, READY_TO_LAND_STATUSES } from "./workspace-phase";
 import { fetchHostMergePreview, workspacePathWithinBase } from "./workspace-probe";
 import type { WorkspaceMergePreview, WorkspaceRecord } from "./types";
+import { STEWARD_WAKE_COOLDOWN_MS, workspaceAutoMergeEnabled } from "./config";
 
 // Don't re-wake the managed steward for the same workspace more than once per this
 // window — a persistent conflict/behind row would otherwise re-ping every sweep.
-const STEWARD_WAKE_COOLDOWN_MS = Number(process.env.AGENT_RELAY_STEWARD_WAKE_COOLDOWN_MS) || 10 * 60 * 1000;
-
 // Wake the managed per-repo steward (issue #167) for a workspace it should handle:
 // auto-provision the policy from global steward config, then queue a `policy:` wake
 // message (which also spawns the on-demand agent now via onMessageForPolicy). Honors a
@@ -176,7 +175,7 @@ const repoMergeRunning = new Map<string, { rerun: boolean }>();
 
 export function scheduleRepoMerge(repoRoot: string | undefined): void {
   if (!repoRoot) return;
-  if (process.env.AGENT_RELAY_WORKSPACE_AUTO_MERGE === "0") return;
+  if (!workspaceAutoMergeEnabled()) return;
   const existing = repoMergeRunning.get(repoRoot);
   if (existing) { existing.rerun = true; return; }
   const state = { rerun: false };
@@ -200,7 +199,7 @@ export function resetRepoMergeSchedulerForTests(): void { repoMergeRunning.clear
 // Drain the landable rows for ONE repo (the event-driven fast path). Scoped to the
 // repo whose ready/settle event fired so it doesn't re-probe every other repo's worktrees.
 async function autoMergeForRepo(repoRoot: string): Promise<LandSweepResult> {
-  if (process.env.AGENT_RELAY_WORKSPACE_AUTO_MERGE === "0") return emptyLandSweep();
+  if (!workspaceAutoMergeEnabled()) return emptyLandSweep();
   const orchestrators = listOrchestrators().filter((orch) => orch.status === "online" && orch.apiUrl);
   if (!orchestrators.length) return emptyLandSweep();
   const candidates = listWorkspaces({ repoRoot }).filter(
@@ -215,7 +214,7 @@ async function autoMergeForRepo(repoRoot: string): Promise<LandSweepResult> {
 // with no agent turn. Scans EVERY repo's landable rows; the per-repo lease still caps
 // it at one dispatch per repo per sweep, and the on-settle re-trigger drains the rest fast.
 export async function autoMergeCleanFastForwards(): Promise<Record<string, unknown>> {
-  if (process.env.AGENT_RELAY_WORKSPACE_AUTO_MERGE === "0") return { skipped: "disabled" };
+  if (!workspaceAutoMergeEnabled()) return { skipped: "disabled" };
   const orchestrators = listOrchestrators().filter((orch) => orch.status === "online" && orch.apiUrl);
   if (!orchestrators.length) return { scanned: 0, skipped: "no online orchestrators" };
 

package/src/workspace-claim.ts

@@ -1,11 +1,10 @@
 import type { WorkspaceRecord } from "./types";
+import { STEWARD_CLAIM_TTL_MS } from "./config";
 
 // A steward claims a workspace before validating/landing so the deterministic
 // auto-merge (Layer 0) doesn't race it (#208 / steward report §1). The claim is a
 // TTL'd lease stored in row metadata, so a dead steward can't block the workspace
 // forever — it expires and auto-merge resumes. Renew by re-claiming.
-const STEWARD_CLAIM_TTL_MS = Number(process.env.AGENT_RELAY_WORKSPACE_CLAIM_TTL_MS) || 15 * 60_000;
-
 interface WorkspaceClaim {
   by?: string;
   purpose?: string;

package/src/workspace-orphans.ts

@@ -28,14 +28,13 @@ import { isPathWithinBase } from "./utils";
 import { TERMINAL_WORKSPACE_STATUSES, worktreeReapable, type WorktreeReapState } from "./workspace-phase";
 import { isOwnerAlive, liveAgentCwds, worktreeInUseByLiveAgent } from "./workspace-merge";
 import { applyWorkspaceAction } from "./workspace-actions";
+import { UNLANDED_FLAG_COOLDOWN_MS, orphanGraceMs, orphanWorktreeReapEnabled, relayToken } from "./config";
 
 // Don't re-flag the same un-landed orphan every sweep — surface it once, then
 // stay quiet for this window. In-memory (keyed by worktree path) like the
 // orphaned-session reaper: a restart re-announces, which is acceptable noise.
-const UNLANDED_FLAG_COOLDOWN_MS = Number(process.env.AGENT_RELAY_ORPHAN_FLAG_COOLDOWN_MS) || 6 * 60 * 60 * 1000;
 // Set AGENT_RELAY_ORPHAN_WORKTREE_REAP=0 to detect + report orphans but never
 // remove them (parity with the session reaper's detect-only switch).
-const orphanWorktreeReapEnabled = () => process.env.AGENT_RELAY_ORPHAN_WORKTREE_REAP !== "0";
 const flaggedAt = new Map<string, number>();
 const IN_FLIGHT_WORKSPACE_STATUSES = new Set<WorkspaceStatus>(["merge_planned", "cleanup_requested"]);
 
@@ -43,10 +42,6 @@ const IN_FLIGHT_WORKSPACE_STATUSES = new Set<WorkspaceStatus>(["merge_planned",
 // reaped after the owner is observed dead continuously for this window, so a
 // reconnecting agent isn't raced. Keyed by resolved worktree path; in-memory like
 // the session reaper's tracker (a restart re-arms the clock — conservative).
-const orphanGraceMs = (): number => {
-  const v = Number(process.env.AGENT_RELAY_ORPHAN_GRACE_MS);
-  return Number.isFinite(v) && v >= 0 ? v : 30 * 60 * 1000;
-};
 const deadOwnerTracker = new Map<string, { firstSeenDeadAt: number }>();
 
 export function resetOrphanWorktreeStateForTests(): void {
@@ -63,7 +58,7 @@ interface OnlineOrchestrator {
 
 function relayHeaders(): Record<string, string> {
   const headers: Record<string, string> = {};
-  const token = process.env.AGENT_RELAY_TOKEN;
+  const token = relayToken();
   if (token) headers[RELAY_TOKEN_HEADER] = token;
   return headers;
 }

package/src/workspace-probe.ts

@@ -19,6 +19,7 @@ import {
 import { isPathWithinBase } from "./utils";
 import { deriveBranchState } from "./workspace-phase";
 import type { AgentCard, WorkspaceMergePreview, WorkspaceRecord } from "./types";
+import { relayToken } from "./config";
 
 /** True when `path` is the base dir itself or nested inside it (containment via
  * resolve+relative, never string startsWith — see CLAUDE.md path-containment rule). */
@@ -37,7 +38,7 @@ export async function fetchHostMergePreview(
   if (workspace.baseRef) query.set("baseRef", workspace.baseRef);
   if (workspace.baseSha) query.set("baseSha", workspace.baseSha);
   const headers: Record<string, string> = {};
-  const token = process.env.AGENT_RELAY_TOKEN;
+  const token = relayToken();
   if (token) headers[RELAY_TOKEN_HEADER] = token;
   try {
     const res = await fetch(`${apiUrl}/api/workspace/merge-preview?${query.toString()}`, { headers, signal: AbortSignal.timeout(8_000) });