merge: wave 2 executor (01-02) into main

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

paperclip-reference/cli/src/checks/agent-jwt-secret-check.ts

@@ -0,0 +1,40 @@
+import {
+  ensureAgentJwtSecret,
+  readAgentJwtSecretFromEnv,
+  readAgentJwtSecretFromEnvFile,
+  resolveAgentJwtEnvFile,
+} from "../config/env.js";
+import type { CheckResult } from "./index.js";
+
+export function agentJwtSecretCheck(configPath?: string): CheckResult {
+  if (readAgentJwtSecretFromEnv(configPath)) {
+    return {
+      name: "Agent JWT secret",
+      status: "pass",
+      message: "PAPERCLIP_AGENT_JWT_SECRET is set in environment",
+    };
+  }
+
+  const envPath = resolveAgentJwtEnvFile(configPath);
+  const fileSecret = readAgentJwtSecretFromEnvFile(envPath);
+
+  if (fileSecret) {
+    return {
+      name: "Agent JWT secret",
+      status: "warn",
+      message: `PAPERCLIP_AGENT_JWT_SECRET is present in ${envPath} but not loaded into environment`,
+      repairHint: `Set the value from ${envPath} in your shell before starting the Paperclip server`,
+    };
+  }
+
+  return {
+    name: "Agent JWT secret",
+    status: "fail",
+    message: `PAPERCLIP_AGENT_JWT_SECRET missing from environment and ${envPath}`,
+    canRepair: true,
+    repair: () => {
+      ensureAgentJwtSecret(configPath);
+    },
+    repairHint: `Run with --repair to create ${envPath} containing PAPERCLIP_AGENT_JWT_SECRET`,
+  };
+}